Archive Magazine CD 1995

home *** CD-ROM | disk | FTP | other *** search

/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / DrawFiles < prev next >

Wrap

Text File | 1988-12-01 | 16.1 KB | 411 lines

ArcDraw File Format =================== Version Number: 1.07 Introduction ------------ The ArcDraw file format provides an object-oriented description of a graphic image. It represents an object in its editable form, unlike a page-description language such as PostScript which simply describes an image. This document describes the file format, and the rules that should be used in order to render the object on a display device. Parties wishing to define their own object types should use the same approach as for the allocation of SWI numbers [Reference: Arthur/RISC OS Programmer's Reference Manual]. Coordinates ----------- All coordinates within an ArcDraw file are signed 32-bit integers that give absolute positions on a large image plane. The units are 1/(180*256) inches, or 1/640 of a printer's point. When plotting on an Archimedes screen, an assumption is made that one OS-unit on the screen is 1/180 of an inch. This gives an image reaching over half a mile in each direction from the origin. The actual image size (e.g. the page format) is not defined by the file, though the maximum extent of the objects defined is quite easy to calculate. Positive-x is to the right, Positive-y is up. The printed page conventionally has the origin at its bottom left hand corner. When rendering the image on a raster device, the origin is at the bottom left hand corner of a device pixel. Colours ------- Colours are specified in ArcDraw files as absolute RGB values in a 32-bit word. The format is: byte 0: reserved (must be zero) byte 1: unsigned red value byte 2: unsigned green value byte 3: unsigned blue value For colour values, 0 means none of that colour and 255 means fully saturated in that colour. (Aside: the phrase "reserved and must be zero" means: when creating such an object, set to zero when reading such an object, do NOT assume that these fields are zero This allows the fields to be used for future expansion. End aside.) The bytes in a word of an ArcDraw file are in little-endian order, e.g. the lest significant byte appears first in the file. The special value &FFFFFFFF is used in the filling of areas and outlines to mean "transparent". The File Header --------------- The file consists of a header, followed by a sequence of objects. The file header is of the following form. 1-byte ASCII 'D' 1-byte ASCII 'r' 1-byte ASCII 'a' 1-byte ASCII 'w' 1-word major format version stamp - currently 201 (decimal) 1-word minor format version stamp - currently 0 12-byte identity of the program that produced this file. typically 8 ASCII chars, padded with spaces. 4-word bounding box: low x, low y, high x, high y When rendering an ArcDraw file, check the major version number. If this is greater than the latest version you recognise then refuse to render the file (e.g. generate an error message for the user), as an incompatible change in the format has occured. The entire file is rendred by rendering the objects one by one, as they appear in the file. The bounding box indicates the intended image size for this drawing. A Draw file containing a file header but no objects is legal; however, the bounding box is undefined. In particular the 'x0' value may be greater than the 'x1' value (and similarly for the y values). The Object Header ----------------- Each object consists of an object header, followed by a variable amount of data depending on the object type. the object header is of the following form: 1-word object type field 1-word object size: number of bytes in the object, always a multiple of 4 4-word object bounding box: low x, low y, high x, high y The bounding box describes the maximum extent of the rendition of the object: the object cannot affect the appearance of the display outside this rectangle. The upper coordinates are an outer bound, in that the device pixel at (x-low, y-low) may be affected by the object, but the one at (x-high, y-high) may not be. The rendition procedure may use clipping on these rectangles to abandon obviously invisible objects. Objects with no direct effect on the rendition of the file have no bounding box: these will be identified explicitly in the object descriptions that follow. If an unidientified object type field is encountered when rendering a file, ignore the object and contine. The object size field includes the object header. The rest of the data for and object depends on the object type field. The Font Table object --------------------- This object is somewhat special in that only one of it ever appears in an ArcDraw file. It has no direct effect on the appearance of the image, but maps font numbers (used in text objects) to textual names of fonts. It must precede all Text objects. A Font Table object has no bounding box in its object header. object type number: 0 object data: sequence of font number definitions up to 3 zero characters, to pad to word boundary a font number definition consists of: 1 character font number (non-zero) textual name of corresponding font (characters within 32..126) zero character Comparison of font names is case-insensitive. Text objects ------------ object type number: 1 object data: 1-word text colour 1-word text background colour hint 1-word text style 1-word x unsigned nominal size of the font 1-word y unsigned nominal size of the font 2-word x,y coordinates of the start of the text base line characters in the string zero character up to 3 zero characters, to pad to word boundary The character string consists of printing ANSI characters with codes within 32..126 or 128..255. This need not be checked during rendering, but other codes may produce undefined or system-dependent results. The style word consists of the following: bits 0..7: one byte font number bits 8..31: reserved (must be zero) Italic, bold etc. variants are assumed to be distinct fonts. The font number is related to the textual name of a font by a preceding Font Table object within the file (see below). The exception to this is font number 0, which is a system font that is sure to be present. When rendering a draw file, if a font is not recognised, the system font should be used instead. The system font is monospaced, with the gap between letters equal to the x nominal size of the font. The background colour hint can be used by font rendition code when performing anti-aliasing. It is referred to as a hint because it has no effect on the rendition of the object on a "perfect" printer, nevertheless for screen rendition it can improve the appearance of text on coloured backgrounds. The font redition code can assume that the text appears on a background that matches the background colour hint. Path objects ------------ object type number: 2 object data: 1-word fill colour (-1 means do not fill) 1-word outline colour (-1 means no outline) 1-word outline width (unsigned) 1-word path style description optional dash pattern definition sequence of path components. An outline width of 0 means draw the thinnest possible outline that the device can represent. A path component consists of: 1-word tag identifier sequence of 2-word (x,y) coordinate pairs Each tag identifier word consists of: bits 0..7: tag identifier byte bits 8..31: reserved, must be zero Possible tag identifier byte values: 0: end of path: no arguments 2: move to absolute position: followed by x,y pair 5: close current sub-path 8: draw to absolute position: followed by x,y pair 6: bezier curve through two control points, to absolute position: followed by three x,y pairs (Aside: the tag values match the arguments required by the Draw module. This block of memory can be passed directly to the Draw module for rendition, see the relevant documentation for precise rules concerning the appearance of paths. See also manuals on PostScript [Reference: PostScript Language Reference Manual, Addison-Wesley]). The possible set of legal path components in a path object is described as follows. A path consists of a sequence of (at least one) subpaths, followed by an "end of path" path component. A subpath consists of a "move to" path component, followed by a sequence of (at least one) "draw to" and "bezier to" path componenets, followed (optionally) by a "close sub-path" path component. The path style description word is as follows: bits 0..1: join style: 0 = mitred joins 1 = round joins 2 = bevelled joins bits 2..3: end cap style: 0 = butt caps 1 = round caps 2 = projecting square caps 3 = triangular caps bits 4..5: start cap style (same possible values) bit 6: winding rule: 0 = non-zero 1 = even-odd bit 7: dash pattern: 0 = dash pattern missing 1 = dash pattern present bits 8..15: reserved and must be zero bits 16..23: triangle cap width: a value within 0..255, measured in sixteenths of the line width. bits 24..31: triangle cap length: a value within 0..255, measured in sixteenths of the line width. The mitre cut-off value is the PostScript default (e.g. 10). If the dash pattern is present then it is in the following format: 1-word offset distance into the dash pattern to start 1-word number of elements in the dash pattern for each element of the dash pattern, 1-word length of the dash pattern element The dash pattern is reused cyclically along the length of the path, with the first element being filled, the next a gap, and so on. Sprite Objects -------------- object type number: 5 object data: a sprite [Reference: Arthur/RISC OS Programmer's Reference Manual]. This contains a pixelmap image. The image is scaled to entirely fill the bounding box. If the sprite has a palette then this gives absolute values for the various possible pixels. If the sprite has no palette then colours are defined locally. Within RISC OS the available "wimp colours" are used. Group Objects ------------- object type number: 6 object data: 12-byte group object name, padded with spaces. a sequence of other objects. The objects contained within the group will have rectangles contained entirely within the rectangle of the group. Nested grouped objects are allowed. The object name has no effect on the rendition of the object. It should consist entirely of printing characters. It may have meaning to specific editors or programs. It should be preserved when copying objects. If no name is intended, twelve space characters should be used. Tagged object ------------- object type number: 7 object data: 1-word tag identifier object additional data (multiple of 4 in size) To render a Tagged object, simply render the enclosed object. The identifier and additional data have no effect on the rendition of the object. This allows specific programs to attatch meaning to certain objects, while keeping the image renderable. Parties wishing to define their own object tags should use the same approach as for the allocation of SWI numbers. Text area objects --------------- object type number: 9 object data: 1 or more text column objects 1-word zero, to mark the end of the text columns 1-word reserved, which must be zero 1-word reserved, which must be zero 1-word initial text foreground colour 1-word initial text background colour hint the body of the text column: ASCII characters, terminated by a null character. 0..3 null characters to align to a word boundary. A text area contains a number of text columns. The text area has a body of text associated with it, which is partioned between the columns. If there is just one text column object then its bounding box must be exactly coincident with that of the text area. The body of the text is paginated in the columns. Effects such as font settings and colour changes are controlled by escape sequences within the body of the text. All escape sequences start with a backslash character (\); the escape code is case sensitive, though any arguments is has are not. 1. \! <version><newline or /> Must appear at the start of the text, and only there. <version> must be 1. 2. \A<code><optional /> Set alignment. <code> is one of L (left = default), R (right), C (centre), D (double). A change in alignment forces a line break. 3. \B<R><spaces><G><spaces><B><newline or /> Set text background colour hint to the given RGB intensity (or the best available approximation). Each value is limited to 0..255. 4. \C<R><spaces><G><spaces><B><newline or /> Set text foreground colour to the given RGB intensity (or the best available approximation). Each value is limited to 0..255. 5. \D<number><newline or /> Indicates that the text area is to contain <number> columns. Must appear before any printing text. 6. \F<digit*><name><spaces><size>[<spaces><width>]<newline or /> Defines a font reference number. <name> is the name of the font, and <size> its height. <width> may be omitted, in which case the font width and height are the same. Font reference numbers may be reassigned. <digit*> is one or two digits. <size> and <width> are in points. 7. \<digit*><optional /> Selects a font. 8. \L<leading><newline or /> Define the leading in points from the end of the (output) line in which the \L appears. Default 10 points. 9. \M<leftmargin><spaces><rightmargin><newline or /> Defines margins that will be left on either size of the text, from the start of the output line in which the sequence appears. The margins are given in points, and are limited to values > 0. If the sum of the margins is greater than the width of the column, the effects are undefined. Both values default to 1 point. 10. \P<leading><newline or /> Define the paragraph leading in points. Default 10 points. 11. \U<position><spaces><thickness><newline or /> Switch on underlining, at <position> units relative to the character base, and of <thickness> units, where a unit is 1/256 of the current font size. <position> is limited to -128..+127, and <thickness> to 0..255. To turn the underlining off, either give a thickness of 0, or use the command \U. (\U followed by a dot). 12. \V[-]<digit><optional /> Vertical move by the specified number of points. 13. \- Soft hyphen: if a line cannot be split at a space, a hyphen may be inserted at this point instead; otherwise, it has no printing effect. 14. \<newline> Force line break. 15. \\ appears as \ on the screen 16 . \;<text><newline> Comment: ignored. Other escape sequences are flagged as errors during verification. Lines within a paragraph are split either at a space, or at a soft hyphen, or (if a single word is longer than a line) at any character. A few other characters have a special interpretation: 1. Control characters are ignored, except for tab, which is replaced by a space. 2. Newlines (that are not part of an escape sequence) are interpreted as follows: a. occuring before any printing text. A paragraph leading is inserted for each newline. b. in the body of the text. A single newline is replaced by a space, except when it is already followed or preceded by a space or tab. A sequence of n newlines inserts a space of (n-1) time the paragraph leading, except that paragraph leading at the top of a new text column is ignored. Lines which protrude beyond the limits of the box vertically, e.g. because the leading is too small are not displayed; however, any font changes, colour changes, etc. in the text are applied. Characters should not protrude horizontally beyond the limits of the text column, e.g. due to italic overhang for this font being greater than the margin setting. Restrictions: if a chunk of text contains more than 16 colour change sequences, only the last 16 will be rendered correctly. This is a consequence of the size of the colour cache used within the font manager. A chunk in this case means a block of text up to anything that forces a line break, e.g. the end of a paragraph or a change on the alignment. Text column objects ----------------- object type number: 10 object data: none A text column object may only occur within a text area object. Its use is described in the section on text area objects.